home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Aminet 2
/
Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso
/
Aminet
/
text
/
misc
/
makeguide1_49b.lha
/
readme.amiga
< prev
next >
Wrap
Text File
|
1992-11-25
|
11KB
|
222 lines
makeinfo 1.49
A modified GNU makeinfo by Reinhard Spisser and Sebastiano Vigna
November 1992
This program is distributed under the GNU General Public License. Please
refer to the COPYING file for details.
If you want to write your own Texinfo documentation (and not just converting
pre-existing Texinfo docs), you will need the GNU Texinfo distribution,
available on many ftp sites (e.g., prep.ai.mit.edu). This distribution
archive contains also an executable version of texindex, so that you don't
need any other file in order to fully exploit Texinfo. Should this
distribution archive not contain the full sources of texindex and makeinfo,
you can get them by sending a self-addressed, stamped envelope and a disk to
either one of the authors, or by searching for the complete distribution on
an ftp site.
(Note that from this release makeinfo is a Release 2 only program, but you
won't need the ixemul.library, because makeinfo has been compiled under the
GNU 2.2 port by Davide Pasetto of Agemo [available at the ftp site
amiga.physik.unizh.ch]; for the same reason, you can stop at any time the
program via CTRL-C, or suspend it in wait state via CTRL-D; in the latter
case, you can resume via CTRL-E).
This project started with the idea of bringing to the Amiga community a set
of tools which would have greatly simplified the handling of on-line help as
opposed to a printed manual. Currently, the Amiga programmer has to keep two
separate files which have to be updated in parallel. If also some hypertext
feature is desired, the document writer has to keep a third version of the
file (since AmigaGuide® is still not enough spread that one can assume the
user will have it somehow).
This is unbearable. And indeed, the GNU people have found a great way of
working around this problem. It's called Texinfo.
A Texinfo document is written in a very simple dialect of TeX that is easy
to learn and use, and it's specifically tailored for the creation of
technical manuals. Texinfo focuses on logical aspects---so the @t{} command,
which typeset in fixed width font whatever is in the braces, should be never
used, and rather replaced with @code{}, @file{} or @key{}, depending on the
semantics of the text involved. This also ensures that each user can
customized its Texinfo macros in such a way to spot out specific parts of a
Texinfo file, or to set a different page size, text formatting etc.
Of course, the format has to be rich enough to express all the needs of a
technical manual, and small enough to allow a decent translation of all the
available constructs to plain ASCII (for an hypotetical hypertext viewer).
Also in this respect Texinfo is an excellent balance.
Full documentation is available on how to write a Texinfo document. It is
written, of course, in Texinfo, and is very clear. You should be able to
start authoring a Texinfo document in an hour or so. If you're used to TeX,
ten minutes will suffice. This documentation can be found on most ftp sites
which have GNU stuff. The latest version of Texinfo we know of is 2.16. It's
a final, very stable version.
Once a Texinfo document is ready, it can be converted in one of the
following ways:
1) It can be passed through TeX using the set of macros texinfo.tex. You
will get a beautiful printed manual.
2) It can be passed through the standard makeinfo in its Info mode; it will
generate an Info document (Info is the GNU hypertext reader). This is not
much of interest for you.
3) It can be passed through makeinfo with the --no-headers option; it will
generate an almost plain ASCII text file (cross references and indices will
still be in Info style).
But with our version of makeinfo,
4) It can be passed through makeinfo with the new --amiga option; it will
generate an AmigaGuide® document; cross references, menus and indices will
become buttons.
5) It can be passed through makeinfo with the --amiga --no-headers options;
it will generate a plain ASCII text file.
Thus, you have to maintain just a document in order to produce a printed
manual, on-line hypertext documentation and plain ASCII documentation.
Texinfo of course relies on a series of information you specify, like menus,
cross references, etc., but the amount of work you'll need to do this will
be very small. It also makes a great job in converting to ASCII---for
instance, @emph{} text, which comes out slanted in the manual, is shown with
two asterisk around. We would like to urge all of the Amiga community
programmers, in particular the people distributing documentation as a file,
to start using Texinfo. It will be an enormous quantum leap.
While we were working on the project, it became clear that much more was
possible with this new tool. For instance, all of the GNU software comes
with Texinfo documentation. It was a matter of a couple of minutes to make
the Texinfo manual (500K!) into an AmigaGuide® file that we could browse at
will, in full AmigaGuide® hypertext.
Every port of this kind has of course some kind of tradeoff. Info and
AmigaGuide® have a rather vaste intersection of features, but both have
specific features that can't be mimicked on the other side.
The main design choice at the specification level was that *every* Texinfo
should have been convertible to an AmigaGuide® file. And that *every*
Texinfo file prepared for AmigaGuide® should have been convertible to Info
format (this is essential, e.g., for people doing cross-development).
Fortunately, we were enough lucky: all Info features are translatable in
AmigaGuide® features, excepted for file splitting; but AmigaGuide® doesn't
load a file entirely---just loads a part of it. So even a 1 megabyte
document is not a problem for it. Info instead relies on a splitting
mechanism which is in makeinfo: this mechanism is disabled by the option
--amiga.
There are also a couple of problem with the representation of buttons; Info
does not have "real" buttons---it just put in the text something of the form
"*Note Nodename::". Thus, the aspect of a line in Info or AmigaGuide® is
very different. We chose to put in the button name only the "real title" of
the button, i.e., the destination node name if nothing else is specified, or
the second argument of a @ref, @xref or @pxref command if available.
Moreover, we noted that the absence of "*Note"'s had made the text a bit
unpleasant to read; so we inserted "see" and "See" whenever Texinfo would
have done it in the printed text.
For menus, Texinfo relies on the visualisation of *both* the button name
*and* the destination node name when building indices. Cutting away the
destination node name would have resulted in a horribly looking index. So we
decided to preserve the visualization of the destination node name after a
menu button when building an index. A normal menu will instead show just a
button.
Also, we slightly improved an aspect of @pxref. Since no ending point was
needed before the closing parenthesis, we stripped it off.
All the features of Info which maps to AmigaGuide® have been implemented.
Thus, the Top node of a Texinfo document will become the Main node of the
AmigaGuide® file, the @master command will be set to the name of the Texinfo
file, and the @width command will be set to the value makeinfo is using for
formatting text.
The --no-headers option has now a better behaviour when also --amiga is
selected. "*Note"'s are replaced by "see", etc.. The result is a completely
human readable ASCII file.
It should also be noted that unfortunately Texinfo doesn't have any way of
specifying a *line* in a node. So this feature of AmigaGuide® is not
representable in a Texinfo file. This is indeed the biggest drawback of
using Texinfo for writing AmigaGuide® documents. But we feel that the
advantages are definitely overwhelming.
Due to the fact that AmigaGuide® is rather picky about the characters it
allows in a button name or in a node name, at least for the time being
makeinfo has to replace in a node name every slash or backslash with a dash
and every quotes with a single open quote. Still, names with curly braces in
them will behave incorrectly. But this is an AmigaGuide® problem.
Note that Texinfo doesn't support officially extended or accented
characters. The workaround, for the time being, is to use ASCII extended
characters like à, etc. in the text (in place of the various \`, etc.
commands). Makeinfo will process the document flawlessly, and by including
the amigatexinfo.tex file supplied in this distribution archive *before*
texinfo.tex into your document, Texinfo will typeset correctly the accented
characters (this should work on any TeX system which supports TeX 3.0; we
tried successfully AmigaTeX and PasTeX). We would like to thank Tom Rokicki
for allowing us to distribute the amigatexinfo.tex file, which is based on
the amiga.tex file supplied in the distribution of Radical Eye's AmigaTeX,
and for his invaluable assistance in adapting amiga.tex to Texinfo. Note
also that the first (October) release of makeinfo 1.49 had an incorrect
amiga.tex file, which did not work with many foreign characters.
Finally, we want to describe some bugs we found both in Texinfo and
AmigaGuide®, whose knowledge can be helpful.
AmigaGuide® 33.1369 doesn't work properly if the name of a button contains
an apostrophe ("'"). So you shouldn't use button names containing @code{},
@samp{}, etc. (they are always forbidden in node names, but you can specify
a button name different from the node name in an external reference
command). The workaround is to not use apostrophes in button names
(AmigaGuide® V34 and V39 doesn't suffer from this problem).
Texinfo 2.16 will insert an unnamed TOC entry for the Top node when the
automatic pointer generation feature of makeinfo is used (that is, your Top
node is defined via @node Top followed by @top). You should include the
whole Top node in a @ifinfo/@end ifinfo pair for the time being.
Texinfo 2.16 will print an extra '*' while underlining chapters (when
--no-headers is activated). In particular, a stand-alone asterisk will
appear at the top of the document if you use the @top command.
(These bugs have been reported to GNU, of course).
Good Texinfoing! Please send any bug report or enhancement request to
Reinhard Spisser
Via Bonghi 15
I-20141 Milano MI
BIX: reinhards
INTERNET: rein@bliss.st.dsi.unimi.it
Sebastiano Vigna
Via California 22
I-20144 Milano MI
BIX: svigna
INTERNET: vigna@imiucca.csi.unimi.it
vigna@ghost.sm.dsi.unimi.it
UUCP:cbmehq!cbmita!sebamiga!seba@cbmvax.cbm.commodore.com
...{uunet|pyramid|rutgers}!cbmvax!cbmehq!cbmita!sebamiga!seba
FIDO: 2:332/607.28